home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / util / shell / shtml.lha / shtml.readme < prev    next >
Encoding:
Text File  |  1992-09-02  |  6.9 KB  |  158 lines
  1. shtml: SHell hTML converter, by Chris Underwood.
  2.  
  3. email: csuwz@csv.warwick.ac.uk
  4.   www: http://www.csv.warick.ac.uk/~csuwz/
  5.  
  6. The scenario:
  7.  
  8.  "Hey, what I need is a utility that allows me to read .html files easily and
  9. with low memory overheads. It sounds like an easy enough shell utility. I'll
  10. just check the Aminet."
  11.  
  12. A few downloads later:
  13.  
  14.  "Well, none of them worked... That one didn't seem to do anything, that one
  15. didn't seem to get any of the tags right and cut things rather badly. that one
  16. made horrid thrashing noises, scrambled the screen and then software failed
  17. with uncalled-for violence, and that one invalidated my hard drive. Something
  18. I don't take kindly to. Darn, I'll just have to learn C and write myself one
  19. that works!"
  20.  
  21. So I did. And for lack of a better name, I called it shtml (not that it has
  22. much to do with secure protocols, I just like the sound of it).
  23.  
  24. A better discription:
  25.  
  26. shtml is a small ~15k program written in C, and compiled by the oddest
  27. integrated environment since original AMOS, SAS/C. Don't read oddest=worst
  28. because I actually quite like it (I quite liked AMOS too).
  29. Anyhow, shtml takes an html file (world wide web page) and formats it so that
  30. it is readable as a pure ASCII text file. If none of that makes any sense to
  31. you then you probably won't find a use for it. In this case, go hunting on the
  32. Aminet for some of the other stuff I've written.
  33.  
  34. Installing it:
  35.  
  36. shtml fits perfectly in your c: directory and that's about the only
  37. installation it needs. It can now be used like any other command.
  38.  
  39. Using it:
  40.  
  41. Type at a shell prompt:
  42.  
  43. shtml ?
  44.  
  45. for a command synopsys (usage chart). Just to be akward, I have written this in
  46. Bakus Nauer form (I doubt that's how it's spelled but I don't much care). The
  47. command synopsys given looks like:
  48.  
  49. Usage: shtml (-h|-help)|([-p|=pure] infile.html [outfile.txt])
  50.  
  51. | means 'one or the other', so x|y means type x or y. Not both. Stuff in square
  52. brackets [] means 'optional' and is not required, but can be used as a switch
  53. to turn on or off a certain effect. Standard brackets () are to group a set
  54. of options and are not literal. Therefore, you can type any of the following,
  55. assuming that infile.html exists and the path to outfile.txt also exists:
  56.  
  57. shtml ?
  58. shtml -h
  59. shtml -help
  60. shtml infile.html
  61. shtml infile.html outfile.txt
  62. shtml -p infile.html
  63. shtml -p infile.html outfile.txt
  64. shtml -pure infile.html
  65. shtml -pure infile.html outfile.txt
  66.  
  67. -h and -help both mean the same. They tell shtml to print a fairly short text
  68. explaining itself and how it is used.
  69.  
  70. -p and -pure are also equivilent. The pure flag is used to ask shtml not to
  71. print any text inversion charecters. Normally text is inverted for titles,
  72. hrefs and the irritating blink tag. -pure surpresses this change.
  73.  
  74. infile.html: This is the name (and path if necessary) of the source html file.
  75. You could feed shtml a simple text document and watch it get formatted to the
  76. screen's width if you needed.
  77.  
  78. outfile.txt: This is the name and path of the file to write the output to. If
  79. no file is specified then output goes to stdout (normally the screen). If the
  80. file does not exist then it is created. If the file already exists, it is
  81. overwritten without warning.
  82.  
  83. I have included the file "shtml_me.html" whith which to test this program.
  84. Just type something like "shtml shtml_me.html" in a shell and watch the output.
  85. Type: "type shtml_me.html" to see what the file originally looks like, and why
  86. the shtml command is useful.
  87.  
  88. History:
  89.  
  90. (Like anyone cares about history...)
  91.  
  92. Version 1. What you have with you. It took about 3 days of lazy work to
  93.            develop and wasn't it worth it? Well, you decide.
  94.  
  95. Future:
  96.  
  97. Anyone got any good ideas (constructive please - I do a good critical,
  98. cynical, sarcastic job myself). Anything useful and code-able I'll probably
  99. get round to doing eventually.
  100. On this note, Thanks to Rich Neal for pointing out that comments weren't being
  101. ignored if they had tags nested in them. 5 minuites of coding later they
  102. were completly ignored as they should be.
  103.  
  104. Something that this thing does need is a width specifier. At the moment it is
  105. hard wired into the code with a #define (and it still works if it is
  106. recompiled with a different value - if you need it, do it). It would be quite
  107. easy to make it specifiable in a command line optionbut I can't be arsed atm.
  108. Next revision probably :)
  109.  
  110. I know the <center> tag isn't acted upon, but it would require quite some
  111. re-writing to make this work. It would be nice but it isn't really worth my
  112. effort. Wanna know why it won't be an easy thing to impliment? Well, read
  113. on if you could care less:
  114.  
  115. How it actually works (algorithm and other bad ideas :)
  116.  
  117. The incomming stream of charecters is split into a stream of words that are
  118. handled instantly. A word is either a tag, or it is a string of charecters
  119. separated by whitespace (Space, Return and Tab).
  120. Each word is checked to see if it is a tag. If it is, it is sent to a tag
  121. processor that handles stuff like <br> and <pre>. Any un-recognised tags
  122. are simply ignored and not printed. If a tag such as <title> comes along, the
  123. inverse text code is sent to the outfile. If </title> is then seen, the normal
  124. text mode is entered again.
  125. If the word is not a tag it is simply sent straight to the outfile (or stdout)
  126. with an added space. Before a word is sent, a simple check is made to see if
  127. it fits on the current line. If it doesn't, a newline charecter is sent first.
  128. If the <center> tag where to be implimented the program would need to know
  129. how far to indent the left hand edge before it started printing. To determine
  130. this value, it would need to know the used space on the current line. To know
  131. this value it has to write the line. By the time it is finished it is too late
  132. to indent the left hand edge because the line has been written already. Bummer,
  133. huh?
  134. I could get round this by buffering the current line of output but this was
  135. more trouble than it was worth and I wrote it off at an early stage. (just
  136. before the first usable working version :)
  137.  
  138. bugs:
  139. Well, there shouldn't be too many of these, but some files don't seem to get
  140. correctly formatted at all. I have no idea why. If anyone has a solution then
  141. please contact me. Most things work perfectly though.
  142.  
  143. This program doesn't need much in the way of memory, but it might do something
  144. slightly unsavoury like crashing if it runs out. It might just exit cleanly
  145. mind, I don't know. I've never had that little memory except in my head!
  146.  
  147. I have placed both the compiled (runnable) binary and the ASCII source code
  148. in this archive. Feel free to change/recompile if necessary but do not
  149. redistribute any changed versions. If you make a stunning new feature for
  150. this, mail it to me and I'll make a new version if it really is stunning. I'll
  151. credit any new code or ideas of course.
  152.  
  153. Well, I don't know if you're bored reading all this cak, but I sure am bored
  154. of writing it. If you have any more problems with this, mail me or check out
  155. the code (learn C if necessary).
  156.  
  157. CMU
  158.